feat(onboarding): add goal-driven readiness flow - #613

Problem

New installs could skip a coherent setup path, and the sidebar onboarding checklist did not reliably route users into organization creation, teammate invitation, team usage, or the main-page tour.

The simplified Quick setup page also shifted its primary button label when either terminal action started closing: Button inserted a loading spinner while the arrow remained inside children, widening the centered content group.

Additionally, the sidebar guide was configured to open by default, causing it to reappear on every app launch despite the one-time handoff being persisted. Its upward chevron also read as expansion instead of collapse toward the bottom-bar trigger.

Solution

Rebuild the readiness flow on current develop, keep setup progress resumable, add compact preference setup and an application preview, and turn the sidebar checklist into real navigation with targeted spotlights. The guide opens organization setup, member invitation, Runtime team usage, and the general layout tour without duplicating authoritative domain state. It also adds developer-only scenario controls and localized copy for all supported locales.

The primary Quick setup action now owns its arrow through Button's fixed 16px right icon slot. Complete and Skip share the guarded closing transition, where the spinner replaces that arrow in place; successful persistence navigates once, duplicate actions are ignored, and failure restores both actions for retry.

The guide now starts closed and auto-opens only while the persisted handoff is pending; displaying it consumes the handoff to shown, so later launches remain closed while the manual trigger stays available. The header now uses a downward chevron to indicate collapsing toward the trigger.

Potential risks

The one-time behavior depends on settings persistence. If that write fails, pending is intentionally retained and retried on a later launch; no persistence schema or domain data changed.

The change spans first-run routing, sidebar navigation, organization management presentation, Runtime navigation, and shared dropdown/progress primitives. A changed lazy-loaded surface or stale target could leave a spotlight in fallback mode. Existing organization/runtime data is not mutated by the guide; guide intents are one-shot runtime state. The two packaged desktop E2E specs and post-rebase visual capture remain follow-up evidence; the routing, progress persistence, guide targets, navigation intents, localization, frontend type/lint boundaries, system-services integration, and terminal-action state transitions are covered by the committed test suite and checks. Rollback is a source revert; persisted guide progress uses settings fields with safe defaults and does not migrate domain data.

The closing-layout regression is verified at the rendered Button DOM boundary, including equal idle/loading icon width, but has not been re-recorded in a packaged Tauri window.

Verification

• Conflict-resolution suite: InlineAlert.test.ts, SetupWalkthroughSidebar.test.ts, and SidebarGuideButton.test.ts — 3 files / 15 tests passed on merge commit 60242e583.
• Conflict-resolution pnpm typecheck — passed on merge commit 60242e583.
• Focused Prettier and ESLint checks plus git diff --cached --check — passed.
• Follow-up sidebar-guide lifecycle suite: 3 Vitest files / 18 tests — passed on the latest PR HEAD.
• Focused SidebarGuideButton ESLint and Prettier checks — passed.
• Follow-up pnpm typecheck — passed on the latest PR HEAD.
• 43 changed Vitest files / 178 tests — passed after rebasing onto current develop.
• Follow-up SetupWalkthrough + route suite: 15 files / 54 tests — passed.
• Final follow-up regression rerun: 2 files / 8 tests — passed.
• ESLint over every existing changed JS/TS/JSX/TSX file — passed; follow-up changed files also passed focused ESLint.
• npm run typecheck — passed after the rebase; pnpm run typecheck passed for the follow-up snapshot.
• Focused Prettier check and git diff --check — passed for the follow-up.
• rustfmt --edition 2021 --check src-tauri/crates/system-services/src/app_menu.rs — passed.
• cargo check --manifest-path src-tauri/Cargo.toml -p system_services — passed.
• git diff --check origin/develop...HEAD — passed for the rebuilt PR.
• An obsolete ProgressBar accessibility test from the pre-rebase work was excluded because it contradicted current develop and was unrelated to onboarding; the PR has no net ProgressBar diff.

Not run: tests/e2e/specs/core/setup-walkthrough-shortcut-ui.spec.mjs, tests/e2e/specs/core/setup-walkthrough-ui.spec.mjs, and packaged desktop visual capture across themes/viewport constraints. The browser shell cannot provide the required Tauri runtime.

Integration notes

• Merged current develop at 243b99a0e0fd925097f2d468dd6d25b1e6571c96 via merge commit 60242e583; retained the expanded InlineAlert API and current GitHub timeline copy while preserving the onboarding role and switchMethod behavior.
• Preserved latest background upload and sidebar behavior while layering onboarding role simulation and guide navigation.
• Previous pre-rebuild remote history remains recoverable at backup/junyu-onboarding-readiness-flow-pre-rebuild-20260804.
• Follow-up UI stability commit: bd84e6e.